Skip to main content

What’s New

Qrvey 8.5
Version 8.5 (LTS) of the Qrvey platform is now available to customers. This version includes several new features and performance improvements.
Learn More
End-of-life Schedule
We've added a new article that lists the features and endpoints that have been scheduled for deprecation. All features and endpoints will be supported for (1) year after the release date of the LTS version that contains the alternative.
Learn More
NodeJS Deprecation
AWS has announced that it is deprecating NodeJS 12, 14, and 16. To avoid any issues as a result of this deprecation, upgrade your instances of the Qrvey platform as described in this announcement.
Learn More
Version: 8.5

Dashboard Builder Widget

When embedded in an application, the Dashboard Builder widget enables users to modify existing dashboards or add new dashboards. Dashboards may contain reports, web forms, or other content.

Note: The Dashboard Builder widget replaces the Page Builder widget in Qrvey version 8.0 and later.

Before You Begin

Get the Helper Code

  1. In Qrvey Composer, open Dashboard Builder and display the Dashboard list.
  2. Click the Embedding Options button in the upper right corner of the page, and then click Embed Dashboard Builder. dashboard-builder-widget
  3. A dialog displays with an HTML tag, a JSON configuration object, and the Widget Launcher script tag.
  4. Click Copy to copy the code, and then paste it into your preferred editor.

Embed the HTML tag

Identify where you would like this widget to display in your application, and then add the HTML tag in that location.

The HTML tag for this widget is:

<qrvey-builders settings="config"></qrvey-builders>

Embed the Widget Launcher script tag

Add the widget launcher script tag to your application.

For reference, the launcher script code is:

<script type="text/javascript" src="https://<WIDGETS_URL>/widgets-launcher/app.js"></script>

Set properties in the JSON configuration object

Define the JSON configuration object by starting with the script provided in the helper code, and then adding additional configuration properties as needed. The script provided contains only the required properties. For reference, an example is copied below. The helper code that you obtained above should include the unique values indicated with brackets (“<>”):

<script>
var config = {
api_key: '<API_KEY>',
domain: 'https://<your_qrvey_domain>',
user_id: '<USER_ID>',
app_id: '<APP_ID>'
};
</script>

When complete, add the JSON configuration object to your application.

Configuration Object Properties

The following table lists the general properties associated with this widget.

PropertyValueRequired
api_keyString, Your organization’s unique API key required to access the Qrvey platform. Never expose your organization’s API key to external users. In Production environments, use a secure token (qv_token) to encrypt the API key.Yes, if the qv_token is not provided
qv_tokenString, A secure token encrypted via JWT to authenticate and authorize embedded widgets. Establishes a secure connection between the host application and the Qrvey system. For more information, see Embedding Widgets Using a Security Token.Yes, if the api_key is not provided
app_idString, ID of the Qrvey application containing the dashboard, report, automation, or web form.Yes
domainString, The base URL of your instance of the Qrvey platform.Yes
user_idString, ID of the Qrvey Composer user that owns the application that is being embedded. Optional: You can alternately specify the user ID in a Qrvey session cookie.Yes, if the user_id is not included in a session cookie
clientidString, Unique identifier for the tenant end user. Required for using the End User Personalization and Download Manager features. The clientid must be set to a unique value for each tenant end user.No
timezoneObject <TimezoneConfiguration>, Overrides the time zone setting in Qrvey Admin Center. For more information, see Configuring Time Zone Settings.No
private_pagesBoolean, Predefine the state of new dashboards. If True, new dashboards will be private, if not new dashboards will be public.No
do_not_allowArray<String>, Collection of strings to define permissions (will hide or block some features):

CREATE_CHART: Hide Create Chart button.
USERS_AUTHENTICATION: Hide Authentication tab.
USERS_LIST: Hide Users tab.
GROUPS_CRUD: Hide the actions for create, duplicate or delete groups.
GROUPS_USERS_DETAIL: Hide the users table inside the group detail view.
No
stylesObject, a JSON object with properties that allow users to modify part of the look and feel of the widget. Every property supports a string (hexadecimal color) or the name of a color.

main_color: String
main_text_color: String
secondary_color: String
icon_color: String
tab_bar_color: String
tab_font_color: String
* error_color: String
No
userFiltersArray<Object>, Collection of custom filters that the system will apply to the visualized data. For more information, see Working With Filters in Embedded Scenarios.No
customTokensObject, JSON object used to set custom threshold values in Bullet and Dial charts. For more information, see Using Custom Tokens.No
personalizationObject, JSON object to configure and overwrite the default personalization/customization settings. For more information, see "Configuring Personalization" below.No
authenticatedSession.emailString, Specifies the email address to associate with the widget. If an address is not specified, exports are sent to the email address associated with the user ID.No
themeidString, theme ID to use in the component.No

Configuring Personalization

The personalization object setting controls customization options for the Dashboard Builder widget and supports the following properties at this time:

PropertyDescriptionTypeDefaultRequired
fit_panel_buttonShow the fit to panel button on the panelsbooleantrueNo

Events

The widget supports custom events to update keys of the configuration, you can dispatch an event using your own user interface to modify the behavior.

  • atApplyUserFilters: Enables changes to the “builderFilters” property - the expected value for this property is a reduced version of the filter object. This property is a collection of objects that includes:
    • Operator: defines which operation will be performed with the expressions.
    • Expressions: a collection of objects that contains the questions/column reference, the type of operation applied to the questions, and the values that will be used for filtering.

Code Samples

The following samples demonstrate how this widget can be used in an HTML page.

ImplementationDescriptionFront-end CodeBack-end Code
Basic API KeyThis sample uses a basic API key to embed a full Dashboard Builder widget. It does not encrypt the API key and is not suitable for production environments.codepenn/a
Basic API Key - Single ReportThis sample uses a basic API key to embed a single Dashboard Builder widget. It does not encrypt the API key and is not suitable for production environments.codepenn/a